Related Issues

• partly fixes https://github.com/deepset-ai/haystack-private/issues/450

Proposed Changes:

Docstring-only additions, no behavior change. Added short "why" notes to 5 functions that looked like they could be merged or simplified, but can't:

• default_to_dict/default_from_dict (core/serialization.py) — notes this is the on-disk pipeline YAML format, incompatible with base_serialization's.
• _serialize_value_with_schema (utils/base_serialization.py) — notes it's for runtime values, not Components, and points back to the note above.
• _serializable_value (tracing/utils.py) — notes it's deliberately one-way/lossy, unlike the schema serializer.
• _serialize_content_part (dataclasses/chat_message.py) — notes the short tags are a deliberate hand-writable public format.
• _serialize_object (components/generators/utils.py) — notes it skips private attributes for OpenAI SDK objects, unlike the generic serializer.

These came out of an investigation into duplicated/scattered serialization code (see related PRs). Most of what looked like duplication turned out to be intentional separation — these notes capture the reasoning directly in the code so it doesn't get
"helpfully" merged later.

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I have added unit tests and updated the docstrings.
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test: and added ! in case the PR includes breaking changes.
• I have documented my code.
• I have added a release note file, following the contributors guidelines.
• I have run pre-commit hooks and fixed any issue.